PATHMac OS 8 and 9 Developer Documentation > Human Interface Toolbox > Menu Manager >

Mac OS 8 Menu Manager Reference

WARNING

Menus in a resource must not be purgeable nor should they have the resource lock bit set. They must have resource ID numbers greater than 127. Do not define a "circular" hierarchical menu--that is, a hierarchical menu in which a submenu has a submenu whose submenu is a hierarchical menu higher in the chain.

Figure 1-3 shows the format of a compiled 'MENU' resource.

Figure 1-3  Structure of a compiled menu ('MENU') resource

A compiled version of a 'MENU' resource contains the following elements:

• Menu ID. Each menu in your application should have a unique menu ID (this can be the menu's resource ID). A negative value indicates that the menu (but not a submenu) belongs to a driver such as a desk accessory. A menu ID from 1 through 235 indicates a menu (or submenu) of an application; a menu ID from 236 through 255 indicates a submenu of a driver. Apple reserves the menu ID of 0.
• Placeholder (two integers containing 0) for the menu's width and height. After reading in the resource data, the Menu Manager requests the menu definition function to calculate the width and height of the menu and to store these values in the menuWidth and menuHeight fields of the menu structure.
• Resource ID of the menu's menu definition function; see Menu Definition IDs . If the integer 63 appears here, as specified by the kMenuStdMenuProc constant in the Rez input file, the Menu Manager uses the standard Appearance-compliant menu definition function to manage the menu. If you provide your own menu definition function, its resource ID should appear in this field. After reading in the menu's resource data, the Menu Manager reads in the menu definition function, if necessary. The Menu Manager stores a handle to the menu definition function in the menuProc field of the menu structure.
• Placeholder (an integer containing 0).
• The initial enabled state of the menu and first 31 menu items. This is a 32-bit value, where bits 1-31 indicate if the corresponding menu item is disabled or enabled, and bit 0 indicates whether the menu as a whole is enabled or disabled. The Menu Manager automatically enables menu items greater than 31 when a menu is created.
• The length (in bytes) of the menu title.
• The title of the menu.
• Variable-length data that describes the menu items. If you provide your own menu definition function you can define and provide this data according to the needs of your function. The Menu Manager simply reads in the data for each menu item and stores it as variable data at the end of the menu structure. The menu definition function is responsible for interpreting the contents of the data. For example, the standard menu definition function interprets this data according to the description given in the following paragraphs.
• Placeholder (a byte containing 0) to indicate the end of the menu item definitions.

Figure 1-4 shows the variable-length data portion of a compiled 'MENU' resource that uses the standard menu definition function.

Figure 1-4  Variable-length data portion of a compiled 'MENU' resource

For the standard menu definition function, the variable-length data contains the following elements:

• Length (in bytes) of the menu item's text.
• Text of the menu item.
• A 1-byte field containing one of the following:
• An icon number. The icon number is a number from 1 through 255 (or from 1 through 254 for small or reduced icons). The Menu Manager adds 256 to the icon number to generate the resource ID of the menu item's icon. If a menu item has an icon, you should also provide a 'cicn' , 'SICN' , or an 'ICON' resource with the resource ID equal to the icon number plus 256. If you want the Menu Manager to reduce an 'ICON' resource to the size of a small icon, you must also provide the value 0x1D in the keyboard equivalent field. If you provide a 'SICN' resource, provide 0x1E in the keyboard equivalent field. Otherwise, the Menu Manager looks first for a 'cicn' resource with the calculated resource ID and uses that icon.
• A text encoding value. (Not recommended with Appearance.) If you want the Menu Manager to draw the item's text in a script other than the system script, specify the text encoding here and also provide 0x1C in the keyboard equivalent field. If the script system for the specified script is installed, the Menu Manager draws the item's text using that script.
• 0 (as specified by the noicon constant in a Rez input file) if the menu item doesn't contain an icon and uses the system script.

A menu item can have an icon or be drawn in a script other than the system script, but not both.

• Keyboard equivalent (specified as a 1-byte character). This can be enhanced with modifier key constants in the modifier keys field of the extended menu resource; see 'xmnu' . In some cases, this field may take on one of the following values instead:
• 0x1B (as specified by the constant hierarchicalMenu in a Rez input file) if the item has a submenu. (Not recommended with Appearance.)
• 0x1C if the item uses a script other than the system script. (Not recommended with Appearance.)
• 0x1D if you want the Menu Manager to reduce an 'ICON' resource to the size of a small icon.
• 0x1E if you want the Menu Manager to use an 'SICN' resource for the item's icon.
• 0 (as specified by the nokey constant in a Rez input file) if the item has neither a keyboard equivalent nor a submenu and uses the system script.

The values 0x01 through 0x1A as well as 0x1F and 0x20 are reserved for use by Apple; your application should not use any of these reserved values in this field.

• A 1-byte field containing one of the following:
• A marking character. Special marking characters are available to indicate the marks associated with a menu item.
• The menu ID of the item's submenu. (Not recommended with Appearance.) Submenus of an application should have menu IDs from 1 through 235; submenus of a driver (such as a desk accessory) should have menu IDs from 236 through 255. If you choose a submenu, you must also set the keyboard equivalent field to 0x1B.
• 0 (as specified by the nomark constant in a Rez input file) if the item has neither a mark nor a submenu.

A menu item can have a mark or a submenu, but not both.

• Font style of the menu item. The constants bold , italic , plain , outline , and shadow can be used in a Rez input file to define their corresponding styles.

If you provide your own menu definition function, you should use the same format for your resource descriptions of menus as shown in Figure 1-3 . You can use the same format or one of your choosing to describe menu items. You can also use bits 1-31 of the enableFlags field of the menu structure as you choose; however, bit 0 must still indicate whether the menu is enabled or disabled.

'xmnu'

You can use the extended menu ( 'xmnu' ) resource to create menus with modifier key keyboard glyphs and icons attached to menu items and Appearance-compliant menu backgrounds. The extended menu resource is available with Appearance Manager 1.0 and later.

After reading in a 'MENU' resource, GetMenu looks for an extended menu resource of type 'xmnu' with the same resource ID. The information is set for specified menu items; it is not necessary to create an extended menu entry for each item. At this point, the information can be purged or released. Figure 1-5 shows the format of a compiled 'xmnu' resource.

Figure 1-5  Structure of a compiled extended menu ('xmnu') resource

A compiled version of an 'xmnu' resource contains the following elements:

• Version number. An integer specifying the version of the resource.
• Number of entries. An integer that specifies the number of entries in the resource. Each entry is an extended menu item structure.
• Extended menu item entries. A series of extended menu item structures, each of which consists of a type, command ID, modifier keys, text encoding, reference constants, menu ID of submenu, font ID, and keyboard glyph.

Figure 1-6 shows the format of an extended menu item entry.

Figure 1-6  Structure of an extended menu item entry

Each entry in a 'xmnu' resource corresponds to a menu item and contains the following:

• Type. An integer that specifies whether there is menu item information for the item in the 'MENU' entry. If this is 0, there is no information for the item in the corresponding 'MENU' entry, and the rest of the record is skipped. If this is 1, there is information for the item in the corresponding 'MENU' entry, and the rest of the record is read.
• Command ID. A unique value which you set to identify the menu item (instead of referring to it using the menu ID and item number). You can also call SetMenuItemCommandID to set the command ID of a menu item. After a successful call to MenuSelect , MenuEvent , or MenuKey , you can call GetMenuItemCommandID to determine its current value.
• Modifier keys. A mask that determines which modifier keys are used in a keyboard equivalent to select a menu item; see Modifier Key Mask Constants .
• Reserved. Set to 0.
• Reserved. Set to 0.
• Text encoding. A long integer which indicates the text encoding which your item text will use. Use currScript for the default text encoding. To change this value, call SetMenuItemTextEncoding . You can call GetMenuItemTextEncoding to determine its current value. This should be used instead of setting a menu item's modifier key to 0x1C and its icon ID to the script code.
• If you wish the text of the menu item to use the system script, this value should be -1. This should be used as the default.
• If you wish the text of the menu item to use the current script, this value should be -2.
• Reference constant. Any value that an application wishes to store. To change this value, call SetMenuItemRefCon . You can call GetMenuItemRefCon to determine its current value.
• Reference constant. Any additional value that an application wishes to store. To change this value, call SetMenuItemRefCon2 . You can call GetMenuItemRefCon2 to determine its current value.
• Menu ID of submenu. A value between 1 and 235, identifying the application submenu.
• Font ID. An integer representing the ID of the font family. If this value is 0, then the system font ID is used.
• Keyboard glyph. A symbol representing a menu item's modifier key. In Appearance 1.0, if the value in this field is zero, the keyboard glyph uses the system font. In Appearance 1.0.1, if the value in this field is zero, the keyboard glyph uses the keyboard font; see Table 1-1 . Use of the keyboard font (rather than the system font) provides a consistent user interface across applications, since a modifier key's symbol will not change regardless of what system font is running. If the value in this field is nonzero, you can override the character code to be displayed with a substitute glyph.
• Reserved. Set to 0.

Table 1-1  Keyboard font character codes

Character code	Description
0x00	Null (always glyph 1)
0x01	Unassigned (reserved for 2 bytes)
0x02	Tab to the right key (for left-to-right script systems)
0x03	Tab to the left key (for right-to-left script systems)
0x04	Enter key
0x05	Shift key
0x06	Control key
0x07	Option key
0x08	Null (always glyph 1)
0x09	Space (always glyph 3) key
0x0A	Delete to the right key (for right-to-left script systems)
0x0B	Return key (for left-to-right script systems)
0x0C	Return key (for right-to-left script systems)
0x0D	Nonmarking return key
0x0E	Unassigned
0x0F	Pencil key
0x10	Downward dashed arrow key
0x11	Command key
0x12	Checkmark key
0x13	Diamond key
0x14	Apple logo key (filled)
0x15	Unassigned (paragraph in Korean)
0x16	Unassigned
0x17	Delete to the left key (for left-to-right script systems)
0x18	Leftward dashed arrow key
0x19	Upward dashed arrow key
0x1A	Rightward dashed arrow key
0x1B	Escape key
0x1C	Clear key
0x1D	Unassigned (left double quotes in Japanese)
0x1E	Unassigned (right double quotes in Japanese)
0x1F	Unassigned (trademark in Japanese)
0x61	Blank key
0x62	Page up key
0x63	Caps lock key
0x64	Left arrow key
0x65	Right arrow key
0x66	Northwest arrow key
0x67	Help key
0x68	Up arrow key
0x69	Southeast arrow key
0x6A	Down arrow key
0x6B	Page down key
0x6C	Apple logo key (outline)
0x6D	Contextual menu key
0x6E	Power key
0x6F	F1 key
0x70	F2 key
0x71	F3 key
0x72	F4 key
0x73	F5 key
0x74	F6 key
0x75	F7 key
0x76	F8 key
0x77	F9 key
0x78	F10 key
0x79	F11 key
0x7A	F12 key
0x87	F13 key
0x88	F14 key
0x89	F15 key
0x8A	Control key (ISO standard)